
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>--_interactive Mode &#8212; Universal Ctags 0.3.0 documentation</title>
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.3.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Choosing a proper parser in ctags" href="guessing.html" />
    <link rel="prev" title="Xref output" href="output-xref.html" /> 
  </head>
  <body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="guessing.html" title="Choosing a proper parser in ctags"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="output-xref.html" title="Xref output"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="interactive-mode">
<span id="id1"></span><h1><code class="docutils literal"><span class="pre">--_interactive</span></code> Mode<a class="headerlink" href="#interactive-mode" title="Permalink to this headline">¶</a></h1>
<p>Universal ctags can be run with <code class="docutils literal"><span class="pre">--_interactive</span></code>, which enters a REPL that
can be used programmatically to control ctags generation. In this mode, json
commands are received over stdin, and corresponding responses are emitted over
stdout.</p>
<p>Communication with Universal ctags over stdio uses the <a class="reference external" href="http://jsonlines.org/">json lines</a> format, where each
json object appears on a single line and is terminated with a newline.</p>
<p>When <code class="docutils literal"><span class="pre">ctags</span> <span class="pre">--_interactive</span></code> is invoked, it will emit a single json object to stdout announcing
its name and version. This signals the start of the interactive loop, and the user can begin sending
commands over stdin.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ctags --_interactive
<span class="go">{&quot;_type&quot;: &quot;program&quot;, &quot;name&quot;: &quot;Universal Ctags&quot;, &quot;version&quot;: &quot;0.0.0&quot;}</span>
</pre></div>
</div>
<p>The following commands are currently supported in interactive mode:</p>
<ul class="simple">
<li><a class="reference internal" href="#generate-tags">generate-tags</a></li>
</ul>
<div class="section" id="generate-tags">
<h2>generate-tags<a class="headerlink" href="#generate-tags" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">generate-tags</span></code> command takes two arguments:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">filename</span></code>: name of the file to generate tags for (required)</li>
<li><code class="docutils literal"><span class="pre">size</span></code>: size in bytes of the file, if the contents will be received over stdin (optional)</li>
</ul>
<p>The simplest way to generate tags for a file is by passing its path on filesystem(<code class="docutils literal"><span class="pre">file</span> <span class="pre">request</span></code>). The response will include
one json object per line representing each tag, followed by a single json object with the <code class="docutils literal"><span class="pre">completed</span></code>
field emitted once the file has been fully processed.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s1">&#39;{&quot;command&quot;:&quot;generate-tags&quot;, &quot;filename&quot;:&quot;test.rb&quot;}&#39;</span> <span class="p">|</span> ctags --_interactive
<span class="go">{&quot;_type&quot;: &quot;program&quot;, &quot;name&quot;: &quot;Universal Ctags&quot;, &quot;version&quot;: &quot;0.0.0&quot;}</span>
<span class="go">{&quot;_type&quot;: &quot;tag&quot;, &quot;name&quot;: &quot;foobar&quot;, &quot;path&quot;: &quot;test.rb&quot;, &quot;pattern&quot;: &quot;/^  def foobar$/&quot;, &quot;kind&quot;: &quot;method&quot;, &quot;scope&quot;: &quot;Test&quot;, &quot;scopeKind&quot;: &quot;class&quot;}</span>
<span class="go">{&quot;_type&quot;:&quot;completed&quot;, &quot;command&quot;: &quot;generate-tags&quot;}</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">generate-tags</span></code> command can also be used to generate tags for code which is not present on filesystem(<code class="docutils literal"><span class="pre">inline</span> <span class="pre">request</span></code>). For example,
an IDE might want to generate ctags for an unsaved buffer while the user is editing code. When <code class="docutils literal"><span class="pre">size</span></code> is specified,
the corresponding number of bytes are read over stdin after the json object and newline.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="o">(</span>
<span class="go">  echo &#39;{&quot;command&quot;:&quot;generate-tags&quot;, &quot;filename&quot;:&quot;test.rb&quot;, &quot;size&quot;: 17}&#39;</span>
<span class="go">  echo &#39;def foobaz() end&#39;</span>
<span class="go">) | ctags --_interactive</span>
<span class="go">{&quot;_type&quot;: &quot;program&quot;, &quot;name&quot;: &quot;Universal Ctags&quot;, &quot;version&quot;: &quot;0.0.0&quot;}</span>
<span class="go">{&quot;_type&quot;: &quot;tag&quot;, &quot;name&quot;: &quot;foobaz&quot;, &quot;path&quot;: &quot;test.rb&quot;, &quot;pattern&quot;: &quot;/^def foobaz() end$/&quot;, &quot;kind&quot;: &quot;method&quot;}</span>
<span class="go">{&quot;_type&quot;: &quot;completed&quot;, &quot;command&quot;: &quot;generate-tags&quot;}</span>
</pre></div>
</div>
</div>
<div class="section" id="sandbox-submode">
<span id="id2"></span><h2>sandbox submode<a class="headerlink" href="#sandbox-submode" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">sandbox</span></code> submode can be used with <code class="docutils literal"><span class="pre">--_interactive=sandbox</span></code>.  This
submode will activate a sandbox, to this limits the damage that the
can be achieved when exploiting a buffer overflow in Universal-ctags.</p>
<p>In the sandbox submode ctags can generate tags only for inline
requests because ctags has to use open system call to handle file
requests. The open system call is not allowed in the sandbox.</p>
<p>This feature uses seccomp-bpf, and is only supported on Linux.
To use the submode libseccomp is needed at build-time. If ctags was
built with seccomp support, <code class="docutils literal"><span class="pre">sandbox</span></code> is listed in the output of
<code class="docutils literal"><span class="pre">--list-features</span></code> option.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-features <span class="p">|</span> grep sandbox
<span class="go">sandbox</span>
</pre></div>
</div>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="o">(</span>
<span class="go">  echo &#39;{&quot;command&quot;:&quot;generate-tags&quot;, &quot;filename&quot;:&quot;test.rb&quot;, &quot;size&quot;: 17}&#39;</span>
<span class="go">  echo &#39;def foobaz() end&#39;</span>
<span class="go">) | ctags --_interactive=sandbox</span>
<span class="go">{&quot;_type&quot;: &quot;program&quot;, &quot;name&quot;: &quot;Universal Ctags&quot;, &quot;version&quot;: &quot;0.0.0&quot;}</span>
<span class="go">{&quot;_type&quot;: &quot;tag&quot;, &quot;name&quot;: &quot;foobaz&quot;, &quot;path&quot;: &quot;test.rb&quot;, &quot;pattern&quot;: &quot;/^def foobaz() end$/&quot;, &quot;kind&quot;: &quot;method&quot;}</span>
<span class="go">{&quot;_type&quot;: &quot;completed&quot;, &quot;command&quot;: &quot;generate-tags&quot;}</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#"><code class="docutils literal"><span class="pre">--_interactive</span></code> Mode</a><ul>
<li><a class="reference internal" href="#generate-tags">generate-tags</a></li>
<li><a class="reference internal" href="#sandbox-submode">sandbox submode</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="output-xref.html"
                        title="previous chapter">Xref output</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="guessing.html"
                        title="next chapter">Choosing a proper parser in ctags</a></p>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="guessing.html" title="Choosing a proper parser in ctags"
             >next</a> |</li>
        <li class="right" >
          <a href="output-xref.html" title="Xref output"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2015, Universal Ctags Team.
      Last updated on 19 Dec 2017.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.4.
    </div>
  </body>
</html>